Day 8 : Backstage 內部員工身份認證：從 AD 同步到 SSO 的實施之路 - AD 篇

16th鐵人賽 backstag spotify cncf

jincoco88912

2024-09-17 01:51:58

301 瀏覽

分享至

簡介

為了實現對公司員工的身份認證，Backstage 本身在未來也會包含不同平台的微服務，而這些微服務可能也需要身份認證的功能，加上公司本身就有許多不同的系統，因此我們計畫實做 SSO 單點登入的功能，而來到 Backstage 這邊，由於架構上的規則，使用者在登入時必須對應到一個實體，難道我們需要一個一個手動建立數百個使用者實體嗎？這時候，可以利用 Backstage 同步 AD 端的員工資料，再自動創建使用者實體，再配合 OIDC 協議實做 SSO，登入時應映射回傳的 mail 達到自動登入。

AD (Active Directory)

圖片來源 - https://borosan.gitbook.io/lpic2-exam-guide/2104-configuring-an-openldap-server

首先我們必須簡單理解 AD 是什麼，Active Directory (AD) 是由 Microsoft 提供的一種目錄服務，用來管理網路中的使用者、電腦設備、群組等等，做為身份驗證、權限控管等。公司就是透過這種方式來管理設備的登入、網頁訪問權限，而我們需要的是 AD 上的員工人員清單。

在 AD 的架構中，可以想像成一個大型的資料夾系統。最上層通常是頂層網域，例如 google.com，這一層包含了整個 AD 的核心系統設定與政策，是所有資料的根基。接下來的一層是組織單位（Organizational Units, OU），通常用來依照部門、職位或地理位置來分類。再往下一層，則是代表員工、設備等具體物件的通用名稱（Common Name, CN）。

每個物件都會有一個唯一的路徑。假設有一個員工的帳號放在公司 IT 部門的 OU 下，那麼這個員工的物件路徑可能會是 CN=Jincoco,OU=IT,DC=google,DC=com。這樣的路徑表示該員工在公司網域內所屬的實際位置，而 Jincoco 中則會包含很多個人相關資訊，例如我們的公司郵件每個人都有，並且是由 attributes 中的使用者名稱加上網域組成的，那透過這個屬性的資料就非常適合來做 Backstage 登入的映射。

AD 安裝大小事

開發測試時可以自行開 VM 虛擬機裝 Windows Server，開啟 ADDS 服務 (Active Directory Domain Services) 也就是 AD 的 Server 端，本篇並不會針對安裝 ADDS 有太多的介紹，詳細安裝方法可以參考最後附上的參考文獻。

本機指向虛擬機 AD

假設安裝完 ADDS 服務後，我們需要將本機設定網域導向，連接到虛擬機上的 AD 伺服器。模擬真實的 AD 環境進行測試，看看能否功能讀取到員工資料。

虛擬機網路設定：
- 將虛擬機的網路模式設置為橋接模式 (Bridged Mode)。這樣虛擬機就會擁有與本機同一網段的 IP 地址，使其在網路上像一台實體伺服器一樣，並且可以直接連線。
取得虛擬機 IP 地址：
- 在虛擬機中打開命令提示字元 (CMD)，使用 ipconfig 指令查詢並記下IPv4 地址，這個要設定到本機的 hosts 檔案。
修改本機的 hosts 檔案：
- 在 Windows 本機上，以管理員身份打開記事本，並編輯 C:\Windows\System32\drivers\etc\hosts 檔案。
- 在檔案中新增一行，將虛擬機的 IP 地址與網域名 test.com 綁定，如此一來本機在解析 testad.com 時，就會指向虛擬機的 AD 伺服器。
```
[虛擬機的IP] testad.com
```
最後在本機 ping 看看網域 testad.com ，如果有回應正確的 ip 地址，目前就成功接通了
設定 ADDS 時指定網域：在設定 ADDS 時，系統會要求要設定一個網域，我們只需要都設定剛剛接通的 test.com 基本上不會有太大問題。

使用 LDAP 連接 AD 測試

既然 ADDS 設定好後，我們可以透過 LDAP (Lightweight Directory Access Protocol) 協議，來快速存取測試，方法可以使用指令或圖形化的應用介面。這邊推薦可以使用圖形化的應用 LDAP Admin 或是直接使用 ldapsearch 指令查詢，成功抓取資料後就可以進行下一步與 Backstage 插件來整合使用。

安裝流程參考資料

可以參考網站中前半段的安裝過程畫面
設定 ADDI Extensions 的 LDAP 連線

Backstage LDAP 插件

幸運的是，在撰寫本篇文章時，這個插件已經經由社群維護，完全遷移到新版 Backstage 架構了，安裝插件的過程也簡單許多，由於現在安裝 Backstage 應用時預設就是使用新版架構，本篇將不會提及以往的做法，關於新舊版差異以及遷移方式將會特別拉出來一篇說明。

根目錄輸入指令安裝，此插件只有後端

yarn --cwd packages/backend add @backstage/plugin-catalog-backend-module-ldap

新增到 packages/backend/src/index.ts

backend.add(import('@backstage/plugin-catalog-backend-module-ldap'));

在 app-config.yaml 中新增與 ADDS 主機連線的相關資訊，因為關係到創建使用者體，理所當然會設定在想 catalog 底下，下列是一些設定上比較需要注意的點：

bind 如果你有測試過 LDAP 的查詢工具就會理解，我們必須以其中一個使用的角度去通過 LDAP 驗證，再查詢所需的資料，而這個角色只需要有足夠權限即可，所以在這邊必須設定一個可通過驗證的使用者帳密。
schedule 很好理解，同步資料的時間週期，基本上正式環境不需要設定太頻繁，除非公司每天都有新的員工加入。
user 則是另一個重點，它指定了要抓取資料的階層範圍，以範例來看：要抓取的就是 IT 的部門資料，而 options 搭配 scope:sub 則會抓取含 IT 以下的所有階層資料。下面的 set map 則是設定當產生實體時，如何去對應抓到的資料，我設定了所有實體都加上了spec.memberOf: ['hitech'] 在元數據文件中，實務上代表大家預設都屬於該組別成員。
map 由於公司的 AD 沒有實際使用 group 的概念，但在 Backstage 的這個插件中沒有設定就會跳錯，所以這邊的 group 就只是意思意思虛設一下的用途，可以不必參考。

catalog:
  providers:
    ldapOrg:
      default:
        target: ldap://example.com
        bind:
          dn: CN=jincoco,OU=IT,DC=example,DC=com
          secret: password
        schedule:
          frequency: { minutes: 10 }
          timeout: { minutes: 10 }
        users:
          dn: OU=IT,OU=HiTech,DC=example,DC=com
          options:
            scope: sub
            filter: (sAMAccountName=*)
            attributes: ['*', '+']
          set:
            spec.memberOf: ['hitech']
          map:
            description: description
            name: sAMAccountName
            displayName: cn
            email: mail
        groups:
          dn: OU=HiTech,DC=example,DC=com
          options:
            scope: sub
            filter: (cn='組')
            attributes: ['*', '+']
          map:
            rdn: cn
            name: name
            displayName: cn

順利的話在啟動 Backstage 時，可以從控制台中看到同步成功的相關 log 訊息。

接著選擇 User 的 Catalog 分類就可以看到同步進來的成員。

點擊查看元數據檔案的架構，與我們設定map 屬性取得的資料，都可以根據自身需求去調整，非常靈活。

Backstage LDAP 身份驗證

我們也可以考慮採用來自第三方開發的登入插件，此插件專為 Backstage 的 LDAP 搭配使用而設計，效果類似於之前實作的 GitHub 身份驗證功能，只不過這個 LDAP Auth 會稍微破壞 Backstage 的身份驗證架構，可能會限制多種登入方式的選擇。在選擇方案前，必須仔細評估實際的環境需求，以確保選擇最適合的模式，本做法可以作為解決方案之一供參考。

https://github.com/immobiliare/backstage-plugin-ldap-auth

結論

在這篇案例中，我們成功使用插件大量產生使用者實體，解決了需要逐一建立使用者資料的問題。這種方式讓我們得以迅速建立員工的資料庫。接下來，我們將結合 OIDC（OpenID Connect）身份驗證，使使用者能夠通過輸入帳號密碼登入系統。這不僅實現了單點登入（SSO）的效果，還能讓使用者在多個已串接身份驗證的平台上無縫切換，非常適合 Backstage 整合多方服務的跨平台架構。